package cc.shacocloud.kotlin.tools.uitls

/**
 * 存储多个值的 `Map` 接口的扩展。
 * @author 思追(shaco)
 */
interface MultiValueMap<K, V> : MutableMap<K, MutableList<V>> {

    /**
     * 返回给定键的第一个值
     *
     * @param key 键
     * @return 指定键的第一个值，如果没有，则为 `null`
     */
    fun getFirst(key: K): V?

    /**
     * 将给定的单个值添加到给定键的当前值列表中
     *
     * @param key   键
     * @param value 值
     */
    fun add(key: K, value: V)

    /**
     * 将给定列表的所有值添加到给定键的当前值列表中
     *
     * @param key    键
     * @param values 值
     */
    fun addAll(key: K, values: List<V>)

    /**
     * 将给定 `MultiValueMap` 的所有值添加到当前值
     */
    fun addAll(values: MultiValueMap<K, V>)

    /**
     * 仅当映射[.containsKey]不存在时 使用 [.add]添加 给定值，
     */
    fun addIfAbsent(key: K, value: V) {
        if (!containsKey(key)) {
            add(key, value)
        }
    }

    /**
     * 在给定键下设置给定的单个值
     */
    fun set(key: K, value: V)

    /**
     * 在下面设置给定的值
     */
    fun setAll(values: Map<K, V>)

    /**
     * 返回一个 `Map`，其中包含此 `MultiValueMap` 中包含的第一个值
     *
     * @return 此地图的单值表示形式
     */
    fun toSingleValueMap(): Map<K, V>

}
